home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 526-550 / disk_530 / dme / doc / arexxmac.doc < prev    next >
Text File  |  1992-05-06  |  9KB  |  218 lines
  1. This is the first general release (vX.29c), of Matt Dillon's DME editor
  2. with an interface to Bill Hawes' ARexx REXX language interpreter, and is
  3. functionally identical to Matt's v1.29c release (excepting the ARexx
  4. interface, of course).
  5.  
  6. ARexx/REXX provides a powerful macro control language capability that can be
  7. added to just about any application ... pretty easily, as it turns out.
  8.  
  9. I chose to add it's macro facilities to my favorite editor for a couple of
  10. reasons.  First, as an exercise, to find out just how to interface ARexx to
  11. an application, and second to make true named macros available to DME.
  12.  
  13. I think I've managed to do both, and would now like for other people to have
  14. a bash at it, and see what I've overlooked.
  15.  
  16. With that in mind, here are a few, uh, implementation notes.  I solicit your
  17. feedback.  Thanks!
  18.  
  19.  
  20.      0 - The following included ARexx macros actually do something useful
  21.      (though relatively simple).  They work, and are setup to process
  22.      any ARexx generated or DME generated error conditions (such as
  23.      not having enough room to save a file to).  At this time, some
  24.          of the error messages that DME puts in the titlebar, may get
  25.          overwritten by an "OK" message.  This is due to the limited number
  26.          of changes that were made to the DME code, and should improve in
  27.          subsequent releases.  See further remarks on error handling below.
  28.  
  29.      The useful macros are: save.dme, put.dme, putd.dme, get.dme, and
  30.      bot.dme.  They are implementations of the VM/CMS XEDIT functions
  31.      of the similar names.
  32.  
  33.      Any other included macros (.dme files) are mostly nonsense as far
  34.      as functionallity.  They were used in helping be to help debug the
  35.      interface, and are included only to illustrate some of the things
  36.      one might do (like nested macro calls, etc).  So be kind about
  37.      them :-)!
  38.  
  39.  
  40.      1 - ARexx macros for DME must be named the same as the command string
  41.      that will be be used to invoke them.
  42.  
  43.  
  44.      2 - ARexx macros for DME should be given the filename extension ".dme".
  45.  
  46.  
  47.      3 - ARexx macros for DME must reside in the current directory, or the
  48.      directory "rexx:" is assigned to.  The current directory is searched
  49.      first, followed by the "rexx:" directory.
  50.  
  51.  
  52.      4 - ARexx macros for DME may be invoked in three ways:
  53.  
  54.      a - Explicitly, using one of the DME "rx" commands (e.g., "rx macname",
  55.          "rx1 macname arg", or "rx2 macname arg1 arg2").
  56.  
  57.          The "rx" command is used to call an ARexx command without passing
  58.          it any arguments; the "rx1" and "rx2" commands are used to pass
  59.          the ARexx macro one or two arguments respectively.  If more args
  60.          need to be passed to the ARexx macro, rx1 (or rx2) may be used by
  61.          quoting them  E.g., to pass a macro 5 args, you might use the
  62.          command: "rx2 macname (arg1 arg2) `arg3 arg4 arg5'", or possibly:
  63.          "rx1 macname (arg1 arg2 arg3 arg4 arg5)".  The "args.dme" macro
  64.          is included for you to experiment with.
  65.  
  66.          These forms may be embedded in a DME command string (e.g.,
  67.          "bottom rx macname find foo" works), unlike the implicit form of
  68.          invocation below.
  69.  
  70.  
  71.      b - Implicitly, by specifying the name of a macro on DME's command
  72.          line, followed by any arguments to be passed to the macro.
  73.  
  74.          The macro name must be the first (or only) token in the command
  75.          string (e.g., "macname huey dewey louie"), and must NOT be the
  76.          same as an internal DME command.
  77.  
  78.          Note that the entire command string is passed to the ARexx
  79.          interperter "as is", with the case of any arguments, special
  80.          characters, etc. being preserved.
  81.  
  82.  
  83.      c - By keystroke.  The implicit form of a macro command line, with
  84.          any arguments, may be mapped to a key just as a DME command is.
  85.          Currently however, partial bindings are not supported.  That is,
  86.          "escimm" cannot be used to bind the macro name to a key, leaving
  87.          the argument(s), if any, to added in the command line.  This
  88.          will be fixed in a future release.
  89.  
  90.          The explicit forms ("rx macname", etc.) may be bound in any
  91.          command sequence.
  92.  
  93.  
  94.      5 - Macro files may contain DME commands, or other macro names.  There
  95.      is currently no "depth checking", nor checking for circular calls
  96.      (A calls B, with B calling A).  If you create such things, you will
  97.      probably get what you deserve :-)!
  98.  
  99.      Also, I think there is a problem in getting arguments for a second
  100.      macro that are specified in the first macro passed back thru DME and
  101.      on to the second macro.  I'm investigating this.
  102.  
  103.      Note that ARexx capitalizes arguments that are to be passed to DME
  104.      if they are not quoted.  So if you want to give the command: find Foo,
  105.      specify it as: find "Foo".  Otherwise you'll be looking for: FOO.
  106.  
  107.  
  108.      6 - Hitting Ctrl-C will result in an "invalid message packet" error
  109.      message from ARexx (code = 10).  This doesn't seem to cause any
  110.      problems, but to avoid it, remap c-c to the new "null" command
  111.      (which does absolutely nothing functional [i.e., map c-c `null'],
  112.      or some other DME command.
  113.  
  114.  
  115.      7 - I have not tested to see if explicit ARexx macro calls work inside
  116.      of complex DME macros, nor with the $scanf facility.
  117.  
  118.  
  119.      8 - Error handling is not all it should be.  Second level (or lower)
  120.      macro error messages (in the title bar), may be overwritten by
  121.      a higher level "OK" (or other message).
  122.  
  123.      Not all DME commands return completion codes, and the "sense" of
  124.      them is opposite that of ARexx (in DME, failure = 0, success = 1).
  125.      This makes figuring out who did what, what worked and what didn't,
  126.      and what went wrong, a little difficult.  I'm sure I don't have it
  127.      all "right" (and probably *can't* without alot of work to DME,
  128.      which I explicitely don't want to do ... yet, anyway).
  129.  
  130.          I have the general definition of an error handling strategy roughed
  131.          out (see the rexx.h file), but am still considering alternatives.
  132.          This is likely to change, so don't count on the proposed method
  133.          just yet.
  134.  
  135.      The binding to the ARexx ErrorMsg() function isn't working with
  136.      Manx yet (because I need to change the "rexxglue" binding, I think).
  137.      So right now I don't display the actual ARexx error messages, and
  138.      have to give you just the code.
  139.  
  140.      This whole area needs lots of work ...
  141.  
  142.  
  143.      9 - Yes, I know the title bar blinking while a macro is running can be
  144.      distracting.  At least you can sorta see what's happening if *you*
  145.      don't blink :-).
  146.  
  147.  
  148.     10 - Compiled using Manx v3.60a (v3.40a/b works too).
  149.  
  150.  
  151.     11 - To compile, set AREXX to 1 in defs.h, and "make rexx".  Set AREXX
  152.          to 0, and use "make norexx"  to create a non-ARexx, vanilla version.
  153.  
  154.      The Makefiles assume you have a precompiled header file in vd0:include
  155.      called "symbols.m" (all of the Amiga .h's).  Also you need to have
  156.      the rexx includes in the "include/rexx" directory, and Matt's sup32lib
  157.          includes in "include/sup32".  His "sup32.lib" should be in the current
  158.      directory, or in the directory with teh Manx libs.
  159.  
  160.      For linking, the "rexxbind.o" file is needed.  When make processes
  161.      "rexxbind.asm", you'll need to be sure your assembly language .i
  162.          files are available to the assembler.
  163.  
  164.  
  165.     12 - The ARexx interface adds about 1.5K to the size of the executable
  166.      right now.
  167.  
  168.      This can probably be reduced a little, by removing some of the checking
  169.          done in "rexx.c" following some of the calls to the ARexx functions
  170.          that create/initialize the messages sent to ARexx.  They're just in
  171.          there for CYA at the moment (I think).
  172.  
  173.  
  174.     13 - This implementation uses the COMMAND interface described in the
  175.      ARexx documentation (as opposed to the FUNCTION interface).
  176.  
  177.  
  178.     14 - ARexx is a Copyrighted product by William S. Hawes,  PO Box 308,
  179.      Maynard, MA  01754 (617-568-8695), and is available from him with
  180.      complete documentation for $49.95 U.S. (plus $2 shipping).
  181.  
  182.      It is a very good product, and well worth the money.  *Please* do
  183.      not pirate it!  I've received written permission from Bill allowing
  184.      the redistribution of his include files with DME, or other example
  185.      code, however please note that these files are still Copyrighted
  186.      by Bill, and that if *you* want to distribute them with *your* own
  187.          application, you should obtain your own permission from Bill to
  188.          do so.
  189.  
  190.  
  191.     15 - DME is a Copyrighted, freely redistributable program by Matt
  192.      Dillon, of Berkeley, CA.  It may be distributed for non-profit
  193.      only.    Obviously, I think it's the best editor currently available
  194.      for the Amiga ... otherwise I wouldn't have gone to the trouble to
  195.      add the ARexx interface.
  196.  
  197.      My code falls under the same distribution restrictions as Matt's;
  198.      you may redistribute it freely, but may not use it for profit, nor
  199.      imbed it in a commercial product without prior written permission
  200.      from me.
  201.  
  202.  
  203.     16 - Please report any problems or bugs found in this version to me at
  204.      the address below, and don't bug Matt about them.  He doesn't have
  205.      ARexx (yet), and won't be able to help you out.
  206.  
  207.  
  208. Good luck ... I hope you find the ARexx interface a useful enhancement!
  209.  
  210. /kim   03/31/88
  211.  
  212.  
  213. UUCP:  kim@amdahl.amdahl.com
  214.   or:  {sun,decwrl,hplabs,pyramid,ihnp4,uunet,oliveb,cbosgd,ames}!amdahl!kim
  215. DDD:   408-746-8462
  216. USPS:  Amdahl Corp.  M/S 249,  1250 E. Arques Av,  Sunnyvale, CA 94086
  217.  
  218.